Enterprise Operations, both CygNet Native Operations and CygNet Business Objects, are based on some common fundamental concepts. Familiarity with these concepts enhances usage of Enterprise Operations.
There are additional CygNet Native Operations concepts, and CygNet Business Object concepts specific to the operation type.
Concepts common to all Enterprise Operations include the following:
Schema files (.xsd) are provided as a reference to the schema structure, filters, and constraints for all Enterprise Operations requests. The CygNet Native schemas and the Business Object Interface schemas stand alone and do not reference one another. The individual XSDs are specific to the type of Enterprise Operation. Native schema files are statically defined and are compiled into the Enterprise Operations EIE, whereas Business Object schema files are dynamically created during the startup process of the Enterprise Gateway or Enterprise Operations EIE.
All Enterprise Operations utilize Request and Response files to store the files containing the XML requests and the XML responses for retrieval.
An Enterprise Operations request file must be a well-formed XML document that adheres to the Enterprise Operations schema. Request files are placed into a folder in the file system directory.
A request generally includes parameters or service filters to limit the data for the operation, as well as a list of attributes to return. For example, the GetAlarmHistory request can include parameters that define the date range of alarms. Sample documents are provided.
An example of a well-formed request XML document that adheres to the Enterprise Objects schema is shown below.
Example
|
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjects811"> <UpdatePointReq> <SvcName>TRAIN22.UIS</SvcName> <Tag>TRAIN22.UIS:TRAIN22_METER_RFLOW</Tag> <ConfigurationParameters> <PointComment>This is a sample comment.</PointComment> </ConfigurationParameters> <RealtimeParameters> <PointValue>1234</PointValue> </RealtimeParameters> </UpdatePointReq> </CygNetEnterpriseOperations> |
An Enterprise Operations response file is an XML document that contains the requested data and/or information regarding the success or failure of the transaction. Response files are placed into a folder in the file system directory by the Enterprise Operations EIE.
An example of a response XML document from a successful operation is shown below.
Example
|
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjects730"> <UpdatePointResp> <OperationResults success="true" resp_timestamp="2011-04-07T20:02:49.703Z" exec_duration="PT0.011S" /> </UpdatePointResp> </CygNetEnterpriseOperations> |
An example of a response XML document from a failed operation is shown below.
Example
|
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjects721"> <UpdatePointResp> <OperationResults success="false" resp_timestamp="2011-04-07T20:04:16.054Z" exec_duration="PT0.010S"> <OperationResult type="ERROR" code="15012">TRAIN22.PNT' returned error (15012) 'Tag not found'</OperationResult> </OperationResults> </UpdatePointResp> </CygNetEnterpriseOperations> |
Request and Response files must be defined using XML and can be created using any text editor, such as Notepad, or an XML editor such as XML Shell or XML Spy. An XML editor helps catch common syntax and structure errors.
Enterprise Operations request files are able to be processed when the Enterprise Operations EIE has access to the Services providing the data necessary for processing the requests. Native Operations use Service Filters to specify the Services that are allowed to provide data for the requests, while Business Object Operations specify the Services in the Business Object Interfaces. The access to services is inclusive; only those services purposely added to the Service Filter, or added to the Business Object Interface, are allowed to provide data for processing of the request.
The Service Filters and the Business Object Interfaces are defined in the Enterprise Operations device instance in the DDS.
Operations request or response documents can be configured to require validation against the Enterprise Operations XML schema definition (XSD) before the operation can be processed. The XSD is maintained by the Enterprise Operations EIE. Enabling validation of XML requests and responses is recommended.
Attributes to export are determined by the configurations of the enabled operations and the services allowed to provide data for processing the operation requests. Operations are enabled in the device instance in the DDS. Native Operations can be enabled on the Native Operations page, and Business Object Operations can be enabled on the Business Objects page.
If a new file is given a name which already exists in a directory, a file name collision will occur. The manner in which you choose to resolve the collision can be configured in the device properties.
The User ID can be configured to be read from the UIS, from the XML request file, or as otherwise specified in the device properties.
Expiration is used to manage the size of the queue by specifying the amount of time the queue will hold operation request messages. Once a message exceeds the period specified, it will be deleted from the queue.
Expiration options allow you to express the specific time frame for which an operation is valid. Options are as follows.
| Option | Description |
|---|---|
|
ExpirationSeconds |
Specifies the time the request is valid after the request file is created in the input directory, expressed in number of seconds. If the request is executed after the specified time, it will be rejected. The default is 86,400 seconds (24 hours). |
|
ExpirationDateTime |
Includes an explicit date and time after which the request will be considered expired. |
|
ExpirationIgnore |
If set to "True" the request never expires. The default is "False" |
Point in time can be specified by including a timestamp, which can be absolute or relative. CygNet-based relative timestamps can be used for both absolute and calculated DateTime values.
An absolute timestamp is an actual date and time (for example, 04/15/2011 09:00).
A relative timestamp is days from today (date only; no time specification).
Example
|
<PointRealtimeFilter> <SingleExpr compare="GT" qualify"Timestamp"> <PointTimestamp>d-1 H=8 M=0 S=0</PointTimestamp> </SingleExpr> </PointRealtimeFilter> |
See Timestamps in the Date and Time section for more information about CygNet timestamps.
Operations which update, add, or delete multiple records must first check the existence of each record in the target work list. If one or more records do not exist (or already exist in the "add" case), the pre-check detects a "partial failure" and the default behavior is to abort the operation.
CygNet gives you the option to continue the operation, despite a partial failure. In the operation request directives, the possible actions for AllowPartialFailure are as follows.
| Action | Description |
|---|---|
|
AllowPartialFailure=False |
Abort before attempting any add/update/delete operation. |
|
AllowPartialFailure=True |
Continue with the operation and allow partial success. Note: Records that do not exist, or already exist in the "add" case, will generate warnings in the results. |
If the service providing data for processing the request does not have a defined relationship with the service to which the request applies, an error will occur.
Example
If the Enterprise Operations device is running in MYSITE.UIS, and the request is to get value history records points that are served by ACME.UIS, an error will occur because MYSITE.UIS and ACME.UIS do not have a defined relationship.
Another error that may occur is a security error. In an Enterprise Operations device, you must opt-in for all services that are authorized to provide data for processing a request. If a service has not been authorized, the request will fail. The opt-in settings are included on the Options page in the device properties box.
Failed operation requests generate an error message.
History Rollup attributes can be configured in some Enterprise Operations, as specified in the operation request. Business Object history rollups can be specified in the Business Object Mapping on the Edit page.
See History Rollups in the History section for more information.
More:
CygNet Native Operations Concepts
CygNet Business Object Concepts
|
|
|
